{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "ee-api-colab-setup.ipynb",
      "provenance": [],
      "collapsed_sections": [],
      "toc_visible": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    }
  },
  "cells": [
    {
      "cell_type": "code",
      "metadata": {
        "id": "krsLgVBYZw_A"
      },
      "source": [
        "#@title Copyright 2019 Google LLC. { display-mode: \"form\" }\n",
        "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "# https://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License."
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aV1xZ1CPi3Nw"
      },
      "source": [
        "<table class=\"ee-notebook-buttons\" align=\"left\"><td>\n",
        "<a target=\"_blank\"  href=\"http://colab.research.google.com/github/google/earthengine-api/blob/master/python/examples/ipynb/ee-api-colab-setup.ipynb\">\n",
        "    <img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" /> Run in Google Colab</a>\n",
        "</td><td>\n",
        "<a target=\"_blank\"  href=\"https://github.com/google/earthengine-api/blob/master/python/examples/ipynb/ee-api-colab-setup.ipynb\"><img width=32px src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" /> View source on GitHub</a></td></table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LAZiVi13zTE7"
      },
      "source": [
        "# Earth Engine Python API Colab Setup\n",
        "\n",
        "This notebook demonstrates how to setup the Earth Engine Python API in Colab and provides several examples of how to print and visualize Earth Engine processed data."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a69CuP5Q6OI7"
      },
      "source": [
        "## Import API and get credentials\r\n",
        "\r\n",
        "The Earth Engine API is installed by default in Google Colaboratory so requires only importing and authenticating. These steps must be completed for each new Colab session, if you restart your Colab kernel, or if your Colab virtual machine is recycled due to inactivity."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SNh-QBc36Mvk"
      },
      "source": [
        "### Import the API\r\n",
        "\r\n",
        "Run the following cell to import the API into your session."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "65RChERMzQHZ"
      },
      "source": [
        "import ee"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "s-dN42MTzg-w"
      },
      "source": [
        "### Authenticate and initialize\n",
        "\n",
        "Run the `ee.Authenticate` function to authenticate your access to Earth Engine servers and `ee.Initialize` to initialize it. Upon running the following cell you'll be asked to grant Earth Engine access to your Google account. Follow the instructions printed to the cell."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "NMp9Ei9b0XXL"
      },
      "source": [
        "# Trigger the authentication flow.\n",
        "ee.Authenticate()\n",
        "\n",
        "# Initialize the library.\n",
        "ee.Initialize()"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8I_Fr0L5AFmu"
      },
      "source": [
        "## Test the API\n",
        "\n",
        "Test the API by printing the elevation of Mount Everest."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "v7pD6pDOAhOW"
      },
      "source": [
        "# Print the elevation of Mount Everest.\n",
        "dem = ee.Image('USGS/SRTMGL1_003')\n",
        "xy = ee.Geometry.Point([86.9250, 27.9881])\n",
        "elev = dem.sample(xy, 30).first().get('elevation').getInfo()\n",
        "print('Mount Everest elevation (m):', elev)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fDLAqiNWeD6t"
      },
      "source": [
        "## Map visualization\n",
        "\n",
        "`ee.Image` objects can be displayed to notebook output cells. The following two\n",
        "examples demonstrate displaying a static image and an interactive map.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "45BfeVygwmKm"
      },
      "source": [
        "### Static image\n",
        "\n",
        "The `IPython.display` module contains the `Image` function, which can display\n",
        "the results of a URL representing an image generated from a call to the Earth\n",
        "Engine `getThumbUrl` function. The following cell will display a thumbnail\n",
        "of the global elevation model."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "Fp4rdpy0eGjx"
      },
      "source": [
        "# Import the Image function from the IPython.display module.\n",
        "from IPython.display import Image\n",
        "\n",
        "# Display a thumbnail of global elevation.\n",
        "Image(url = dem.updateMask(dem.gt(0))\n",
        "  .getThumbURL({'min': 0, 'max': 4000, 'dimensions': 512,\n",
        "                'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ljo5dbLkfmVm"
      },
      "source": [
        "### Interactive map\n",
        "\n",
        "The [`folium`](https://python-visualization.github.io/folium/)\n",
        "library can be used to display `ee.Image` objects on an interactive\n",
        "[Leaflet](https://leafletjs.com/) map. Folium has no default\n",
        "method for handling tiles from Earth Engine, so one must be defined\n",
        "and added to the `folium.Map` module before use.\n",
        "\n",
        "The following cell provides an example of adding a method for handing Earth Engine\n",
        "tiles and using it to display an elevation model to a Leaflet map."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "VIiyf6azf4mU"
      },
      "source": [
        "# Import the Folium library.\n",
        "import folium\n",
        "\n",
        "# Define a method for displaying Earth Engine image tiles to folium map.\n",
        "def add_ee_layer(self, ee_image_object, vis_params, name):\n",
        "  map_id_dict = ee.Image(ee_image_object).getMapId(vis_params)\n",
        "  folium.raster_layers.TileLayer(\n",
        "    tiles = map_id_dict['tile_fetcher'].url_format,\n",
        "    attr = 'Map Data &copy; <a href=\"https://earthengine.google.com/\">Google Earth Engine</a>',\n",
        "    name = name,\n",
        "    overlay = True,\n",
        "    control = True\n",
        "  ).add_to(self)\n",
        "\n",
        "# Add EE drawing method to folium.\n",
        "folium.Map.add_ee_layer = add_ee_layer\n",
        "\n",
        "# Set visualization parameters.\n",
        "vis_params = {\n",
        "  'min': 0,\n",
        "  'max': 4000,\n",
        "  'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}\n",
        "\n",
        "# Create a folium map object.\n",
        "my_map = folium.Map(location=[20, 0], zoom_start=3)\n",
        "\n",
        "# Add the elevation model to the map object.\n",
        "my_map.add_ee_layer(dem.updateMask(dem.gt(0)), vis_params, 'DEM')\n",
        "\n",
        "# Add a layer control panel to the map.\n",
        "my_map.add_child(folium.LayerControl())\n",
        "\n",
        "# Display the map.\n",
        "display(my_map)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CYfinjFhg0HN"
      },
      "source": [
        "## Chart visualization\n",
        "\n",
        "Some Earth Engine functions produce tabular data that can be plotted by\n",
        "data visualization packages such as `matplotlib`. The following example\n",
        "demonstrates the display of tabular data from Earth Engine as a scatter\n",
        "plot. See [Charting in Colaboratory](https://colab.sandbox.google.com/notebooks/charts.ipynb)\n",
        "for more information."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "tRPULejJhBSl"
      },
      "source": [
        "# Import the matplotlib.pyplot module.\n",
        "import matplotlib.pyplot as plt\n",
        "\n",
        "# Fetch a Landsat image.\n",
        "img = ee.Image('LANDSAT/LT05/C01/T1_SR/LT05_034033_20000913')\n",
        "\n",
        "# Select Red and NIR bands, scale them, and sample 500 points.\n",
        "samp_fc = img.select(['B3','B4']).divide(10000).sample(scale=30, numPixels=500)\n",
        "\n",
        "# Arrange the sample as a list of lists.\n",
        "samp_dict = samp_fc.reduceColumns(ee.Reducer.toList().repeat(2), ['B3', 'B4'])\n",
        "samp_list = ee.List(samp_dict.get('list'))\n",
        "\n",
        "# Save server-side ee.List as a client-side Python list.\n",
        "samp_data = samp_list.getInfo()\n",
        "\n",
        "# Display a scatter plot of Red-NIR sample pairs using matplotlib.\n",
        "plt.scatter(samp_data[0], samp_data[1], alpha=0.2)\n",
        "plt.xlabel('Red', fontsize=12)\n",
        "plt.ylabel('NIR', fontsize=12)\n",
        "plt.show()"
      ],
      "execution_count": null,
      "outputs": []
    }
  ]
}